Skip to main content

Collection

A collection is a group of requests that will be run asynchronously.

Endpoints​

POST /v1/async/collections​

Creates a new collection.

Once the collection is created, it can be run using the /collections/{collection_id}/run endpoint.

Returns a JSON object containing the ID of the new collection, the collection name, and a success message.

This endpoint requires a body with the following structure:

{
    "name": "New collection",
    "requests": [
        {
            "url": "www.example.com",
            "browser": true,
            "screenshot": false,
            "actions": [
                {
                    "type": "wait-for-timeout",
                    "time": 5000
                }
            ]
        }
    ],
    "callback_url": "https://your-server.com/webhook"
}
  • name: Name of the project or collection.
  • requests: A list of requests. The parameters for this field are detailed in scrape.
  • callback_url (optional): URL to which a POST notification will be sent when a run of this collection completes. The webhook includes event, run_id, status, counters (total_requests, success_requests, failed_requests), and job_ids. Delivery is signed with HMAC-SHA256 (headers X-SP-Signature and X-SP-Timestamp). Can be overridden per run.

GET /v1/async/collections​

This endpoint returns all collections created so far.

Example response:

[
    {
        "name": "new collection",
        "id": "c38b0bcf-cb7c-4728-8704-2c2e267dcff9"
    },
    {
        "name": "new collection 2",
        "id": "11d6f8af-9a54-4b6c-b793-e12b77c86159"
    }
]

GET /v1/async/collections/{collection_id}​

Retrieves the collection whose ID matches the one provided as a parameter.

Response: A JSON object containing the collection's id and name.

Example response:

{
  "id": "c38b0bcf-cb7c-4728-8704-2c2e267dcff9",
  "name": "new collection"
}

PUT /v1/async/collections/{collection_id}​

This endpoint updates a collection with the ID provided as a parameter.

Both the name and the request list can be updated.

Returns a JSON object with the updated collection.

This request requires a body with the following structure:

{
    "name":"Updated collection",
    "requests": [
        {
            "url": "example.com",
            "browser": true,
            "screenshot": false,
            "actions": [
                {
                    "type": "wait-for-timeout",
                    "time": 5000,
                },
            ]
        }
    ]
}
  • name: Name of the project or collection.
  • requests: A list of requests. The parameters for this field are detailed in scrape.

Example response:

{
  "id": "44a8c93d-a35e-4351-9565-7cd93b5ac296",
  "name": "update collection",
  "message": "Collection updated successfully."
}